package com.erlang4j.internal.messages;

import com.erlang4j.api.IGetData;
import com.erlang4j.api.process.IProcessWithState;

/**
 * This is a pattern and a block of code. If the pattern occurs, the block is executed. It is unusual to write one of
 * these directly, as the MessageAdapter is slightly nicer syntax. If you are working with Swing, don't forget to use
 * the SwingMessageAdapter!
 * <p>
 * Design notes
 * <ul>
 * <li>It was tempting to make this an acceptor, but that would have required each handler to be well behaved
 * <li>It was tempting to not include the pattern, and pass the pattern to the IMessageProcessor, however the pattern
 * contains strings (names of variables) that are typically used in the process, so I decided to couple them tightly
 * <li>The process method is allowed to throw exception to make it easier to write the adapters: it stops endless
 * wrapping of exceptions
 * </ul>
 * </p>
 * 
 * @author Phil Rice
 */
public interface IMessageHandler {

	String pattern();

	/**
	 * If this is called, the pattern has matched the OtpErlangObject,
	 * 
	 * @param process
	 *            the current process that the handler is in. This allows you to access and change the default bindings
	 *            (gives the same effect as tail end recursion in Erlang), change the state (if you are in a
	 *            statemachine).
	 * @param data
	 *            holds the map from keys to the variables that where in the OtpErlangObject. It also allows you to
	 *            change the behaviour of the pattern matcher a little
	 */
	void process(IProcessWithState process, IGetData data) throws Exception;
}
